﻿/*****************************************************************************

   Project:   WP7AppLifecycleService
   File:      IPageStateHandler.cs 
   Creator:   David Carballo (dacarb@gmail.com)
   
   Description:
      Definition of IPageStateHandler interface.

   (C) Copyright 2011, David Carballo
       http://wp7applifecycle.codeplex.com/license

******************************************************************************/

namespace WP7AppLifecycleService
{
    /// <summary>
    /// Interface that needs to be implemented by classes
    /// responsible of saving the data of a page, the page state, when the
    /// application is tombstoned, and restoring such data when the app comes back to life
    /// after having been tombstoned. An example would be the scrolling position inside a list.
    /// </summary>
    /// <remarks>It would be desirable to be able to use PhoneApplicationPage.State in the implementation
    /// of methods, but due to implementation details when data needs to be restored it won´t be available.
    /// </remarks>
    public interface IPageStateHandler
    {
        /// <summary>
        /// Saves the page state when the application is tombstoned.
        /// </summary>
        /// <param name="state">A <see cref="System.Collections.Generic.IDictionary{String, Object}"/> instance
        /// that can be used to store the page state.</param>
        /// <remarks>It would be desirable to be able to use PhoneApplicationPage.State in the implementation
        /// of methods, but due to implementation details when data needs to be restored it won´t be available.
        /// </remarks>
        void SavePageState(System.Collections.Generic.IDictionary<string, object> state);

        /// <summary>
        /// Restores the data of the page when the application comes back to life
        /// after having been tombstoned.
        /// </summary>
        /// <param name="state">A <see cref="System.Collections.Generic.IDictionary{String, Object}"/> instance
        /// that can be used to restore the page state.</param>
        /// <remarks>PhoneApplicationPage.State is not available.</remarks>
        void RestorePageState(System.Collections.Generic.IDictionary<string, object> state);

        /// <summary>
        /// Deletes any state saved when the application was tombstoned. 
        /// <para>This method will automatically be called right after RestoreApplicationState is
        /// successfully executed.</para>
        /// </summary>
        /// <param name="state">A <see cref="System.Collections.Generic.IDictionary{String, Object}"/> instance
        /// that can be used to store the page state.</param>
        /// <remarks>PhoneApplicationPage.State is not available.</remarks>
        void DeletePageState(System.Collections.Generic.IDictionary<string, object> state);
    }
}
